<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-type" content="text/html; charset=iso-8859-1">
<title>Using the Standard Converters - The Java EE 5 Tutorial</title>
<meta name="robots" content="index,follow">
<meta name="robots" content="index,follow">
<meta name="date" content="2008-10-01">
<link rel="stylesheet" type="text/css" href="css/default.css">
<link rel="stylesheet" type="text/css" href="css/ipg.css">
<link rel="stylesheet" type="text/css" href="css/j5eetutorial.css">
</head>

<body>

<table border="0" cellpadding="5" cellspacing="0" width="100%">
<tbody>
   <tr valign="top">
      <td><p class="toc level1"><a href="docinfo.html">Document Information</a></p>
<p class="toc level1 tocsp"><a href="gexaf.html">Preface</a></p>
<p class="toc level1 tocsp"><a href="gfirp.html">Part&nbsp;I&nbsp;Introduction</a></p>
<p class="toc level2"><a href="bnaaw.html">1.&nbsp;&nbsp;Overview</a></p>
<p class="toc level2"><a href="gfiud.html">2.&nbsp;&nbsp;Using the Tutorial Examples</a></p>
<p class="toc level1 tocsp"><a href="bnadp.html">Part&nbsp;II&nbsp;The Web Tier</a></p>
<p class="toc level2"><a href="bnadr.html">3.&nbsp;&nbsp;Getting Started with Web Applications</a></p>
<p class="toc level2"><a href="bnafd.html">4.&nbsp;&nbsp;Java Servlet Technology</a></p>
<p class="toc level2"><a href="bnagx.html">5.&nbsp;&nbsp;JavaServer Pages Technology</a></p>
<p class="toc level2"><a href="bnajo.html">6.&nbsp;&nbsp;JavaServer Pages Documents</a></p>
<p class="toc level2"><a href="bnakc.html">7.&nbsp;&nbsp;JavaServer Pages Standard Tag Library</a></p>
<p class="toc level2"><a href="bnalj.html">8.&nbsp;&nbsp;Custom Tags in JSP Pages</a></p>
<p class="toc level2"><a href="bnaon.html">9.&nbsp;&nbsp;Scripting in JSP Pages</a></p>
<p class="toc level2"><a href="bnaph.html">10.&nbsp;&nbsp;JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="bnaqz.html">11.&nbsp;&nbsp;Using JavaServer Faces Technology in JSP Pages</a></p>
<p class="toc level3"><a href="bnara.html">The Example JavaServer Faces Application</a></p>
<p class="toc level3"><a href="bnarb.html">Setting Up a Page</a></p>
<p class="toc level3"><a href="bnarc.html">Using the Core Tags</a></p>
<p class="toc level3"><a href="bnarf.html">Adding UI Components to a Page Using the HTML Component Tags</a></p>
<p class="toc level4"><a href="bnarf.html#bnarg">UI Component Tag Attributes</a></p>
<p class="toc level5"><a href="bnarf.html#bnarh">The <tt>id</tt> Attribute</a></p>
<p class="toc level5"><a href="bnarf.html#bnari">The <tt>immediate</tt> Attribute</a></p>
<p class="toc level5"><a href="bnarf.html#bnarj">The <tt>rendered</tt> Attribute</a></p>
<p class="toc level5"><a href="bnarf.html#bnark">The <tt>style</tt> and <tt>styleClass</tt> Attributes</a></p>
<p class="toc level5"><a href="bnarf.html#bnarl">The <tt>value</tt> and <tt>binding</tt> Attributes</a></p>
<p class="toc level4 tocsp"><a href="bnarf.html#bnarm">Adding a Form Component</a></p>
<p class="toc level4"><a href="bnarf.html#bnaro">Using Text Components</a></p>
<p class="toc level5"><a href="bnarf.html#bnarr">Rendering a Text Field with the <tt>inputText</tt> Tag</a></p>
<p class="toc level5"><a href="bnarf.html#bnars">Rendering a Label with the <tt>outputLabel</tt> Tag</a></p>
<p class="toc level5"><a href="bnarf.html#bnart">Rendering a Hyperlink with the <tt>outputLink</tt> Tag</a></p>
<p class="toc level5"><a href="bnarf.html#bnaru">Displaying a Formatted Message with the <tt>outputFormat</tt> Tag</a></p>
<p class="toc level5"><a href="bnarf.html#bnarv">Rendering a Password Field with the <tt>inputSecret</tt> Tag</a></p>
<p class="toc level4 tocsp"><a href="bnarf.html#bnarw">Using Command Components for Performing Actions and Navigation</a></p>
<p class="toc level5"><a href="bnarf.html#bnarx">Rendering a Button with the <tt>commandButton</tt> Tag</a></p>
<p class="toc level5"><a href="bnarf.html#bnary">Rendering a Hyperlink with the <tt>commandLink</tt> Tag</a></p>
<p class="toc level4 tocsp"><a href="bnarf.html#bnarz">Using Data-Bound Table Components</a></p>
<p class="toc level4"><a href="bnarf.html#bnasb">Adding Graphics and Images with the <tt>graphicImage</tt> Tag</a></p>
<p class="toc level4"><a href="bnarf.html#bnasc">Laying Out Components with the <tt>UIPanel</tt> Component</a></p>
<p class="toc level4"><a href="bnarf.html#bnase">Rendering Components for Selecting One Value</a></p>
<p class="toc level5"><a href="bnarf.html#bnasg">Displaying a Check Box Using the <tt>selectBooleanCheckbox</tt> Tag</a></p>
<p class="toc level5"><a href="bnarf.html#bnash">Displaying a Menu Using the <tt>selectOneMenu</tt> Tag</a></p>
<p class="toc level4 tocsp"><a href="bnarf.html#bnasi">Rendering Components for Selecting Multiple Values</a></p>
<p class="toc level4"><a href="bnarf.html#bnask">The <tt>UISelectItem</tt>, <tt>UISelectItems</tt>, and <tt>UISelectItemGroup</tt> Components</a></p>
<p class="toc level5"><a href="bnarf.html#bnasm">Using the <tt>selectItems</tt> Tag</a></p>
<p class="toc level5"><a href="bnarf.html#bnasn">Using the <tt>selectItem</tt> Tag</a></p>
<p class="toc level4 tocsp"><a href="bnarf.html#bnaso">Displaying Error Messages with the <tt>message</tt> and <tt>messages</tt> Tags</a></p>
<p class="toc level3 tocsp"><a href="bnasp.html">Using Localized Data</a></p>
<p class="toc level4"><a href="bnasp.html#bnasq">Loading a Resource Bundle</a></p>
<p class="toc level4"><a href="bnasp.html#bnasr">Referencing Localized Static Data</a></p>
<p class="toc level4"><a href="bnasp.html#bnass">Referencing Error Messages</a></p>
<div class="onpage">
<p class="toc level3 tocsp"><a href="">Using the Standard Converters</a></p>
<p class="toc level4"><a href="#bnasu">Converting a Component's Value</a></p>
<p class="toc level4"><a href="#bnasv">Using <tt>DateTimeConverter</tt></a></p>
<p class="toc level4"><a href="#bnasx">Using <tt>NumberConverter</tt></a></p>
</div>
<p class="toc level3 tocsp"><a href="bnasz.html">Registering Listeners on Components</a></p>
<p class="toc level4"><a href="bnasz.html#bnata">Registering a Value-Change Listener on a Component</a></p>
<p class="toc level4"><a href="bnasz.html#bnatb">Registering an Action Listener on a Component</a></p>
<p class="toc level3 tocsp"><a href="bnatc.html">Using the Standard Validators</a></p>
<p class="toc level4"><a href="bnatc.html#bnate">Validating a Component's Value</a></p>
<p class="toc level4"><a href="bnatc.html#bnatf">Using the <tt>LongRangeValidator</tt></a></p>
<p class="toc level3 tocsp"><a href="bnatg.html">Binding Component Values and Instances to External Data Sources</a></p>
<p class="toc level4"><a href="bnatg.html#bnati">Binding a Component Value to a Property</a></p>
<p class="toc level4"><a href="bnatg.html#bnatj">Binding a Component Value to an Implicit Object</a></p>
<p class="toc level4"><a href="bnatg.html#bnatl">Binding a Component Instance to a Bean Property</a></p>
<p class="toc level3 tocsp"><a href="bnatm.html">Binding Converters, Listeners, and Validators to Backing Bean Properties</a></p>
<p class="toc level3"><a href="bnatn.html">Referencing a Backing Bean Method</a></p>
<p class="toc level4"><a href="bnatn.html#bnatp">Referencing a Method That Performs Navigation</a></p>
<p class="toc level4"><a href="bnatn.html#bnatq">Referencing a Method That Handles an Action Event</a></p>
<p class="toc level4"><a href="bnatn.html#bnatr">Referencing a Method That Performs Validation</a></p>
<p class="toc level4"><a href="bnatn.html#bnats">Referencing a Method That Handles a Value-change Event</a></p>
<p class="toc level3 tocsp"><a href="bnatt.html">Using Custom Objects</a></p>
<p class="toc level4"><a href="bnatt.html#bnatu">Using a Custom Converter</a></p>
<p class="toc level4"><a href="bnatt.html#bnatv">Using a Custom Validator</a></p>
<p class="toc level4"><a href="bnatt.html#bnatw">Using a Custom Component</a></p>
<p class="toc level2 tocsp"><a href="bnatx.html">12.&nbsp;&nbsp;Developing with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="bnavg.html">13.&nbsp;&nbsp;Creating Custom UI Components</a></p>
<p class="toc level2"><a href="bnawo.html">14.&nbsp;&nbsp;Configuring JavaServer Faces Applications</a></p>
<p class="toc level2"><a href="bnaxu.html">15.&nbsp;&nbsp;Internationalizing and Localizing Web Applications</a></p>
<p class="toc level1 tocsp"><a href="bnayk.html">Part&nbsp;III&nbsp;Web Services</a></p>
<p class="toc level2"><a href="bnayl.html">16.&nbsp;&nbsp;Building Web Services with JAX-WS</a></p>
<p class="toc level2"><a href="bnazf.html">17.&nbsp;&nbsp;Binding between XML Schema and Java Classes</a></p>
<p class="toc level2"><a href="bnbdv.html">18.&nbsp;&nbsp;Streaming API for XML</a></p>
<p class="toc level2"><a href="bnbhf.html">19.&nbsp;&nbsp;SOAP with Attachments API for Java</a></p>
<p class="toc level1 tocsp"><a href="bnblr.html">Part&nbsp;IV&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="bnbls.html">20.&nbsp;&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="bnbnb.html">21.&nbsp;&nbsp;Getting Started with Enterprise Beans</a></p>
<p class="toc level2"><a href="bnboc.html">22.&nbsp;&nbsp;Session Bean Examples</a></p>
<p class="toc level2"><a href="bnbpk.html">23.&nbsp;&nbsp;A Message-Driven Bean Example</a></p>
<p class="toc level1 tocsp"><a href="bnbpy.html">Part&nbsp;V&nbsp;Persistence</a></p>
<p class="toc level2"><a href="bnbpz.html">24.&nbsp;&nbsp;Introduction to the Java Persistence API</a></p>
<p class="toc level2"><a href="bnbrl.html">25.&nbsp;&nbsp;Persistence in the Web Tier</a></p>
<p class="toc level2"><a href="bnbrs.html">26.&nbsp;&nbsp;Persistence in the EJB Tier</a></p>
<p class="toc level2"><a href="bnbtg.html">27.&nbsp;&nbsp;The Java Persistence Query Language</a></p>
<p class="toc level1 tocsp"><a href="bnbwi.html">Part&nbsp;VI&nbsp;Services</a></p>
<p class="toc level2"><a href="bnbwj.html">28.&nbsp;&nbsp;Introduction to Security in the Java EE Platform</a></p>
<p class="toc level2"><a href="bnbyk.html">29.&nbsp;&nbsp;Securing Java EE Applications</a></p>
<p class="toc level2"><a href="bncas.html">30.&nbsp;&nbsp;Securing Web Applications</a></p>
<p class="toc level2"><a href="bncdq.html">31.&nbsp;&nbsp;The Java Message Service API</a></p>
<p class="toc level2"><a href="bncgv.html">32.&nbsp;&nbsp;Java EE Examples Using the JMS API</a></p>
<p class="toc level2"><a href="bncih.html">33.&nbsp;&nbsp;Transactions</a></p>
<p class="toc level2"><a href="bncjh.html">34.&nbsp;&nbsp;Resource Connections</a></p>
<p class="toc level2"><a href="bncjx.html">35.&nbsp;&nbsp;Connector Architecture</a></p>
<p class="toc level1 tocsp"><a href="bnckn.html">Part&nbsp;VII&nbsp;Case Studies</a></p>
<p class="toc level2"><a href="bncko.html">36.&nbsp;&nbsp;The Coffee Break Application</a></p>
<p class="toc level2"><a href="bnclz.html">37.&nbsp;&nbsp;The Duke's Bank Application</a></p>
<p class="toc level1 tocsp"><a href="gexbq.html">Part&nbsp;VIII&nbsp;Appendixes</a></p>
<p class="toc level2"><a href="bncno.html">A.&nbsp;&nbsp;Java Encoding Schemes</a></p>
<p class="toc level2"><a href="bncnq.html">B.&nbsp;&nbsp;Preparation for Java EE Certification Exams</a></p>
<p class="toc level2"><a href="bncnt.html">C.&nbsp;&nbsp;About the Authors</a></p>
<p class="toc level1 tocsp"><a href="idx-1.html">Index</a></p>
</td>
      <td width="10px">&nbsp;</td>
      <td width="705px">
         <div class="header">
             <div class="header-links-top">
                 <a href="http://java.sun.com">java.sun.com</a> |
                 <a href="http://docs.sun.com/">docs.sun.com</a><br>
             </div> 
             <img src="graphics/tutorialBanner.gif" width="704" height="120" alt="The Java&trade; EE 5 Tutorial"/>
             <div class="header-links">
	         <a href="index.html">Home</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/download.html">Download</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/JavaEETutorial.pdf">PDF</a> |
                 <a href="http://java.sun.com/javaee/5/docs/api/index.html">API</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/faq.html">FAQ</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/search.html">Search</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/sendusmail.html">Feedback</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/history.html">History</a>
             </div>
             <div class="navigation">
                 <a href="bnasp.html"><img style="padding-right: 3px" src="graphics/leftButton.gif" border="0"></a>
                 <a href="sjsaseej2eet.html"><img style="padding-right: 3px" src="graphics/upButton.gif" border="0"></a>
                 <a href="bnasz.html"><img style="padding-left: 3px" src="graphics/rightButton.gif" border="0"></a>
             </div>
         </div>

	 <div class="maincontent">      	 
             

<a name="bnast"></a><h3>Using the Standard Converters</h3>
<p><a name="indexterm-1108"></a><a name="indexterm-1109"></a>The JavaServer Faces implementation provides a set of <tt>Converter</tt> implementations that you can use
to convert component data. For more information on the conceptual details of the
conversion model, see <a href="bnaqd.html#bnaqi">Conversion Model</a>.</p><p><a name="indexterm-1110"></a><a name="indexterm-1111"></a>The standard <tt>Converter</tt> implementations, located in the <tt>javax.faces.convert</tt> package, are as follows:</p>
<ul><li><p><a name="indexterm-1112"></a><tt>BigDecimalConverter</tt></p></li>
<li><p><a name="indexterm-1113"></a><tt>BigIntegerConverter</tt></p></li>
<li><p><a name="indexterm-1114"></a><tt>BooleanConverter</tt></p></li>
<li><p><a name="indexterm-1115"></a><tt>ByteConverter</tt></p></li>
<li><p><a name="indexterm-1116"></a><tt>CharacterConverter</tt></p></li>
<li><p><a name="indexterm-1117"></a><tt>DateTimeConverter</tt></p></li>
<li><p><a name="indexterm-1118"></a><tt>DoubleConverter</tt></p></li>
<li><p><a name="indexterm-1119"></a><tt>FloatConverter</tt></p></li>
<li><p><a name="indexterm-1120"></a><tt>IntegerConverter</tt></p></li>
<li><p><a name="indexterm-1121"></a><tt>LongConverter</tt></p></li>
<li><p><a name="indexterm-1122"></a><tt>NumberConverter</tt></p></li>
<li><p><a name="indexterm-1123"></a><tt>ShortConverter</tt></p></li></ul>
<p>Each of these converters has a standard error message associated with them. If
you have registered one of these converters onto a component on your page,
and the converter is not able to convert the component&rsquo;s value, the converter&rsquo;s
error message will display on the page. For example, the error message that
displays if <tt>BigIntegerConverter</tt> fails to convert a value is:</p><pre>{0} must be a number consisting of one or more digits</pre><p>In this case the <tt>{0}</tt> substitution parameter will be replaced with the name
of the input component on which the converter is registered. See section 2.4.5
of the JavaServer Faces specification, version 1.2, for a complete list of error
messages.</p><p><a name="indexterm-1124"></a><a name="indexterm-1125"></a>Two of the standard converters (<tt>DateTimeConverter</tt> and <tt>NumberConverter</tt>) have their own tags,
which allow you to configure the format of the component data using the
tag attributes. <a href="#bnasv">Using <tt>DateTimeConverter</tt></a> discusses using <tt>DateTimeConverter</tt>. <a href="#bnasx">Using <tt>NumberConverter</tt></a> discusses using <tt>NumberConverter</tt>. The following section
explains how to convert a component&rsquo;s value including how to register the other
standard converters with a component.</p>

<a name="bnasu"></a><h4>Converting a Component&rsquo;s Value</h4>
<a name="indexterm-1126"></a><a name="indexterm-1127"></a><p>To use a particular converter to convert a component&rsquo;s value, you need to
register the converter onto the component. You can register any of the standard
converters on a component in one of four ways:</p>
<ul><li><p>Nest one of the standard converter tags inside the component&rsquo;s tag. These tags are <tt>convertDateTime</tt> and <tt>convertNumber</tt> and are described in <a href="#bnasv">Using <tt>DateTimeConverter</tt></a> and <a href="#bnasx">Using <tt>NumberConverter</tt></a>, respectively.</p></li>
<li><p><a name="indexterm-1128"></a><a name="indexterm-1129"></a>Bind the value of the component to a backing bean property of the same type as the converter.</p></li>
<li><p>Refer to the converter from the component tag&rsquo;s <tt>converter</tt> attribute.</p></li>
<li><p><a name="indexterm-1130"></a><a name="indexterm-1131"></a>Nest a <tt>converter</tt> tag inside of the component tag and use either the <tt>converter</tt> tag&rsquo;s <tt>converterId</tt> attribute or its <tt>binding</tt> attribute to refer to the converter.</p></li></ul>
<p>As an example of the second approach, if you want a component&rsquo;s data
to be converted to an <tt>Integer</tt>, you can simply bind the component&rsquo;s value
to a property similar to this:</p><pre>Integer age = 0;
public Integer getAge(){ return age;}
public void setAge(Integer age) {this.age = age;}</pre><p>If the component is not bound to a bean property, you can
employ the third technique by using the <tt>converter</tt> attribute on the component tag:</p><pre>&lt;h:inputText
    converter="javax.faces.convert.IntegerConverter" /></pre><p><a name="indexterm-1132"></a>This example shows the <tt>converter</tt> attribute referring to the fully-qualified class name of
the converter. The <tt>converter</tt> attribute can also take the ID of the
component. If the converter is a custom converter, the ID is defined in
the application configuration resource file (see <a href="bnawp.html">Application Configuration Resource File</a>).</p><p><a name="indexterm-1133"></a><a name="indexterm-1134"></a><a name="indexterm-1135"></a>The data corresponding to this example <tt>inputText</tt> tag will be converted to a <tt>java.lang.Integer</tt>.
Notice that the <tt>Integer</tt> type is already a supported type of the
<tt>NumberConverter</tt>. If you don&rsquo;t need to specify any formatting instructions using the <tt>convertNumber</tt>
tag attributes, and if one of the other converters will suffice, you can
simply reference that converter using the component tag&rsquo;s <tt>converter</tt> attribute.</p><p><a name="indexterm-1136"></a><a name="indexterm-1137"></a>Finally, you can nest a <tt>converter</tt> tag within the component tag and use
either the converter tag&rsquo;s <tt>converterId</tt> attribute or its <tt>binding</tt> attribute to reference the
converter.</p><p><a name="indexterm-1138"></a><a name="indexterm-1139"></a>The <tt>converterId</tt> attribute must reference the converter&rsquo;s ID. Again, if the converter is
a custom converter, the value of <tt>converterID</tt> must match the ID in the application
configuration resource file; otherwise it must match the ID as defined in the
converter class. Here is an example:</p><pre>&lt;h:inputText value="#{LoginBean.Age}" />
    &lt;f:converter converterId="Integer" />
&lt;/h:inputText></pre><p>Instead of using the <tt>converterId</tt> attribute, the <tt>converter</tt> tag can use the
<tt>binding</tt> attribute. The <tt>binding</tt> attribute must resolve to a bean property that accepts and
returns an appropriate <tt>Converter</tt> instance. See <a href="bnatm.html">Binding Converters, Listeners, and Validators to Backing Bean Properties</a> for more information.</p>

<a name="bnasv"></a><h4>Using <tt>DateTimeConverter</tt></h4>
<p><a name="indexterm-1140"></a><a name="indexterm-1141"></a><a name="indexterm-1142"></a>You can convert a component&rsquo;s data to a <tt>java.util.Date</tt> by nesting the <tt>convertDateTime</tt> tag
inside the component tag. The <tt>convertDateTime</tt> tag has several attributes that allow you to
specify the format and type of the data. <a href="#bnasw">Table&nbsp;11-5</a> lists the attributes.</p><p>Here is a simple example of a <tt>convertDateTime</tt> tag from the <tt>bookreceipt.jsp</tt> page:</p><pre>&lt;h:outputText id= "shipDate" value="#{cashier.shipDate}">
    &lt;f:convertDateTime dateStyle="full" />
&lt;/h:outputText></pre><p>When binding the <tt>DateTime</tt> converter to a component, ensure that the backing bean
property to which the component is bound is of type <tt>java.util.Date</tt>. In the
case of the preceding example, <tt>cashier.shipDate</tt> must be of type <tt>java.util.Date</tt>.</p><p>Here is an example of a date and time that the preceding
tag can display:</p><pre>Saturday, Feb 22, 2003</pre><p>You can also display the same date and time using this tag:</p><pre>&lt;h:outputText value="#{cashier.shipDate}">
    &lt;f:convertDateTime
         pattern="EEEEEEEE, MMM dd, yyyy" />
&lt;/h:outputText></pre><p><a name="indexterm-1143"></a><a name="indexterm-1144"></a>If you want to display the example date in Spanish, you can
use the <tt>locale</tt> attribute:</p><pre>&lt;h:inputText value="#{cashier.shipDate}">
    &lt;f:convertDateTime dateStyle="full"
         locale="Locale.SPAIN"
        timeStyle="long" type="both" />
&lt;/h:inputText></pre><p>This tag would display</p><pre>sabado 23 de septiembre de 2006</pre><p>Please refer to the <i>Customizing Formats</i> lesson of the Java Tutorial at <a href="http://java.sun.com/docs/books/tutorial/i18n/format/simpleDateFormat.html">http://java.sun.com/docs/books/tutorial/i18n/format/simpleDateFormat.html</a> for
more information on how to format the output using the <tt>pattern</tt> attribute of
the <tt>convertDateTime</tt> tag.</p><a name="bnasw"></a><h6>Table&nbsp;11-5 <tt>convertDateTime</tt> Tag Attributes</h6><a name="indexterm-1145"></a><a name="indexterm-1146"></a><table><col width="11%"><col width="20%"><col width="67%"><tr><th align="left" valign="top" scope="column"><p>Attribute</p></th>
<th align="left" valign="top" scope="column"><p>Type</p></th>
<th align="left" valign="top" scope="column"><p>Description</p></th>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>binding</tt></p></td>
<td align="left" valign="top" scope="row"><p><tt>DateTimeConverter</tt></p></td>
<td align="left" valign="top" scope="row"><p>Used to bind a converter to a backing bean property</p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>dateStyle</tt></p></td>
<td align="left" valign="top" scope="row"><p><tt>String</tt></p></td>
<td align="left" valign="top" scope="row"><p>Defines
the format, as specified by <tt>java.text.DateFormat</tt>, of a date or the date part
of a <tt>date</tt> string. Applied only if <tt>type</tt> is <tt>date</tt> (or both) and
<tt>pattern</tt> is not defined. Valid values: <tt>default</tt>, <tt>short</tt>, <tt>medium</tt>, <tt>long</tt>, and <tt>full</tt>.
If no value is specified, <tt>default</tt> is used.</p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>locale</tt></p></td>
<td align="left" valign="top" scope="row"><p><tt>String</tt> or <tt>Locale</tt></p></td>
<td align="left" valign="top" scope="row"><p><a name="indexterm-1147"></a><tt>Locale</tt> whose predefined
styles for dates and times are used during formatting or parsing. If not
specified, the <tt>Locale</tt> returned by <tt>FacesContext.getLocale</tt> will be used.</p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>pattern</tt></p></td>
<td align="left" valign="top" scope="row"><p><tt>String</tt></p></td>
<td align="left" valign="top" scope="row"><p>Custom formatting pattern that
determines how the date/time string should be formatted and parsed. If this attribute
is specified, <tt>dateStyle</tt>, <tt>timeStyle</tt>, and <tt>type</tt> attributes are ignored.</p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>timeStyle</tt></p></td>
<td align="left" valign="top" scope="row"><p><tt>String</tt></p></td>
<td align="left" valign="top" scope="row"><p>Defines the format, as
specified by <tt>java.text.DateFormat</tt>, of a <tt>time</tt> or the time part of a <tt>date</tt>
string. Applied only if <tt>type</tt> is time and <tt>pattern</tt> is not defined. Valid values:
<tt>default</tt>, <tt>short</tt>, <tt>medium</tt>, <tt>long</tt>, and <tt>full</tt>. If no value is specified, <tt>default</tt> is
used.</p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>timeZone</tt></p></td>
<td align="left" valign="top" scope="row"><p><tt>String</tt> or <tt>TimeZone</tt></p></td>
<td align="left" valign="top" scope="row"><p>Time zone in which to interpret any time information in
the <tt>date</tt> string.</p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>type</tt></p></td>
<td align="left" valign="top" scope="row"><p><tt>String</tt></p></td>
<td align="left" valign="top" scope="row"><p>Specifies whether the string value will contain a <tt>date</tt>, a <tt>time</tt>,
or both. Valid values are <tt>date</tt>, <tt>time</tt>, or both. If no value
is specified, <tt>date</tt> is used.</p></td>
</tr>
</table>

<a name="bnasx"></a><h4>Using <tt>NumberConverter</tt></h4>
<p><a name="indexterm-1148"></a><a name="indexterm-1149"></a><a name="indexterm-1150"></a><a name="indexterm-1151"></a><a name="indexterm-1152"></a>You can convert a component&rsquo;s data to a <tt>java.lang.Number</tt> by nesting the <tt>convertNumber</tt>
tag inside the component tag. The <tt>convertNumber</tt> tag has several attributes that allow
you to specify the format and type of the data. <a href="#bnasy">Table&nbsp;11-6</a> lists the
attributes.</p><p>The <tt>bookcashier.jsp</tt> page of Duke&rsquo;s Bookstore uses a <tt>convertNumber</tt> tag to display the
total prices of the books in the shopping cart:</p><pre>&lt;h:outputText value="#{cart.total}" >
    &lt;f:convertNumber type="currency"/>
&lt;/h:outputText></pre><p>When binding the <tt>Number</tt> converter to a component, ensure that the backing bean
property to which the component is bound is of primitive type or has
a type of <tt>java.lang.Number</tt>. In the case of the preceding example, <tt>cart.total</tt> is
of type <tt>java.lang.Number</tt>.</p><p>Here is an example of a number this tag can display</p><pre>$934</pre><p>This number can also be displayed using this tag:</p><pre>&lt;h:outputText id="cartTotal"
     value="#{cart.Total}" >
    &lt;f:convertNumber pattern="
$####"
 />
&lt;/h:outputText></pre><p>Please refer to the <i>Customizing Formats</i> lesson of the Java Tutorial at <a href="http://java.sun.com/docs/books/tutorial/i18n/format/decimalFormat.html">http://java.sun.com/docs/books/tutorial/i18n/format/decimalFormat.html</a> for
more information on how to format the output using the pattern attribute of
the <tt>convertNumber</tt> tag.</p><a name="bnasy"></a><h6>Table&nbsp;11-6 <tt>convertNumber</tt> Attributes</h6><a name="indexterm-1153"></a><a name="indexterm-1154"></a><table><col width="21%"><col width="21%"><col width="56%"><tr><th align="left" valign="top" scope="column"><p>Attribute</p></th>
<th align="left" valign="top" scope="column"><p>Type</p></th>
<th align="left" valign="top" scope="column"><p>Description</p></th>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>binding</tt></p></td>
<td align="left" valign="top" scope="row"><p><tt>NumberConverter</tt></p></td>
<td align="left" valign="top" scope="row"><p>Used to bind a converter to a backing bean property</p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>currencyCode</tt></p></td>
<td align="left" valign="top" scope="row"><p><tt>String</tt></p></td>
<td align="left" valign="top" scope="row"><p>ISO
4217 currency code, used only when formatting currencies.</p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>currencySymbol</tt></p></td>
<td align="left" valign="top" scope="row"><p><tt>String</tt></p></td>
<td align="left" valign="top" scope="row"><p>Currency symbol, applied only when
formatting currencies.</p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>groupingUsed</tt></p></td>
<td align="left" valign="top" scope="row"><p><tt>boolean</tt></p></td>
<td align="left" valign="top" scope="row"><p>Specifies whether formatted output contains grouping separators.</p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>integerOnly</tt></p></td>
<td align="left" valign="top" scope="row"><p><tt>boolean</tt></p></td>
<td align="left" valign="top" scope="row"><p>Specifies whether only the integer
part of the value will be parsed.</p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>locale</tt></p></td>
<td align="left" valign="top" scope="row"><p><tt>String</tt> or <tt>Locale</tt></p></td>
<td align="left" valign="top" scope="row"><p><tt>Locale</tt> whose number styles
are used to format or parse data.</p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>maxFractionDigits</tt></p></td>
<td align="left" valign="top" scope="row"><p><tt>int</tt></p></td>
<td align="left" valign="top" scope="row"><p>Maximum number of digits formatted in the
fractional part of the output.</p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>maxIntegerDigits</tt></p></td>
<td align="left" valign="top" scope="row"><p><tt>int</tt></p></td>
<td align="left" valign="top" scope="row"><p>Maximum number of digits formatted in the integer
part of the output.</p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>minFractionDigits</tt></p></td>
<td align="left" valign="top" scope="row"><p><tt>int</tt></p></td>
<td align="left" valign="top" scope="row"><p>Minimum number of digits formatted in the fractional part
of the output.</p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>minIntegerDigits</tt></p></td>
<td align="left" valign="top" scope="row"><p><tt>int</tt></p></td>
<td align="left" valign="top" scope="row"><p>Minimum number of digits formatted in the integer part of
the output.</p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>pattern</tt></p></td>
<td align="left" valign="top" scope="row"><p><tt>String</tt></p></td>
<td align="left" valign="top" scope="row"><p>Custom formatting pattern that determines how the number string is formatted and
parsed.</p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>type</tt></p></td>
<td align="left" valign="top" scope="row"><p><tt>String</tt></p></td>
<td align="left" valign="top" scope="row"><p>Specifies whether the string value is parsed and formatted as a <tt>number</tt>,
<tt>currency</tt>, or <tt>percentage</tt>. If not specified, <tt>number</tt> is used.</p></td>
</tr>
</table>
         </div>
         <div class="navigation">
             <a href="bnasp.html"><img style="padding-right: 3px" src="graphics/leftButton.gif" border="0"></a>
             <a href="sjsaseej2eet.html"><img style="padding-right: 3px" src="graphics/upButton.gif" border="0"></a>
             <a href="bnasz.html"><img style="padding-left: 3px" src="graphics/rightButton.gif" border="0"></a>
         </div>

         <div class="copyright">
      	    <p>The material in The Java&trade; EE 5 Tutorial is <a href='docinfo.html'>copyright</a>-protected and may not be published in other works without express written permission from Sun Microsystems.</p>
      	 </div>

      </td>
   </tr>
</tbody>
</table>
</body>
</html>

